---
title: 'Cell Selection'
enterprise: true
---

Cell selection allows Excel-like selection of ranges of cells. Cell selections are useful for visually highlighting data, copying data to the [Clipboard](./clipboard/), or for doing aggregations using the [Status Bar](./status-bar/).

## Enabling Cell Selection

Cell Selection is enabled by setting the `gridOptions.cellSelection` to `true`, or to a configuration object.

```{% frameworkTransform=true %}
const gridOptions = {
    cellSelection: true,
}
```

When enabled, ranges can be selected in the following ways:

-   **Mouse Drag:** Click the mouse down on a cell and drag and release the mouse over another cell. A range will be created between the two cells and clear any existing ranges.

-   **Ctrl & Mouse Drag:** Holding {% kbd "^ Ctrl" /%} key while creating a range using mouse drag **outside an existing range** will create a new cell range selection and keep any existing ranges.

-   **Shift & Click:** Clicking on one cell to focus that cell, then holding down {% kbd "⇧ Shift" /%} while clicking another cell, will create a range between both cells.

-   **Shift & Arrow Keys:** Focusing a cell and then holding down {% kbd "⇧ Shift" /%} and using the arrow keys will create a range starting from the focused cell.

-   **Ctrl & Shift & Arrow Keys:** Focusing a cell and then holding down {% kbd "^ Ctrl" /%} + {% kbd "⇧ Shift" /%} and using the arrow keys will create a range starting from the focused cell to the last cell in the direction of the Arrow pressed.

### Cell Range Deselection

It is possible to deselect part of existing ranges in the following ways:

-   **Ctrl & Mouse Drag:** Holding {% kbd "^ Ctrl" /%} and dragging a range starting **within an existing range** will cause any cells covered by the new range to be deselected.

-   **Ctrl & Click:** Holding {% kbd "^ Ctrl" /%} and clicking a cell will deselect just that cell.

Note that deselecting part of a range can split the range into multiple ranges, since individual ranges have the limitation of being rectangular.

The example below demonstrates simple cell selection. Cell ranges can be selected in all the ways described above.

{% gridExampleRunner title="Cell Range Selection and Deselection" name="range-selection" /%}

## Prevent Selection of Multiple Ranges

By default multiple ranges can be selected. To restrict cell selection to a single range, even if the {% kbd "^ Ctrl" /%} key is held down, set `cellSelection.suppressMultiRanges` to `true`.

```{% frameworkTransform=true %}
const gridOptions = {
    cellSelection: {
        suppressMultiRanges: true,
    }
}
```

The following example demonstrates single range cell selection:

{% gridExampleRunner title="Cell Range Selection Suppress Multi" name="range-selection-suppress-multi" /%}

## Selecting Cells via Column Headers

Users can select all visible cells in a column by setting `cellSelection.enableColumnSelection` to `true` and then either clicking a column header.

Normally, when selecting a column, all other ranges are cleared. If you wish to keep existing selections, hold {% kbd "^ Ctrl" /%} and then select a column header.

Cells that have been selected via column selection may be de-selected by holding {% kbd "^ Ctrl" /%} and then clicking the column header.

Users can extend the range of a column selection by holding {% kbd "⇧ Shift" /%} and then clicking on another column header.

When interacting via the keyboard, users may press {% kbd "↵ Enter" /%} while a column header is focussed instead of clicking a column header.

This feature is illustrated in the example below, which uses the following configuration:

```{% frameworkTransform=true %}
const gridOptions = {
    cellSelection: {
        enableColumnSelection: true,
    }
}
```

{% gridExampleRunner title="Cell Selection via Column Headers" name="column-header-cell-selection" /%}

{% note %}
When column selection is enabled, [Row Sorting](./row-sorting) requires holding down the {% kbd "⌥ Alt" /%} key in addition to the normal interaction (i.e. clicking or pressing {% kbd "↵ Enter" /%}). 

Similarly [Column Group Expansion](./column-groups) via keyboard requires holding down the {% kbd "⌥ Alt" /%} key in addition to pressing {% kbd "↵ Enter" /%}.
{% /note %}

## Ranges with Pinned Columns and Rows

It is possible to select a cell range that spans pinned and non-pinned sections of the grid. If you do this, the selected range will not have any gaps with regards to the column or row order. 

For example, if you start the drag on the left pinned area and drag to the right pinned area, then all of the columns in the centre area will also be part of the range. Likewise with pinned rows, no row gaps will occur if a cell range spans into pinned rows. A range will be continuous between the rows pinned to the top, the centre, and the rows pinned to the bottom.

This can be thought of as follows: if you have a grid with pinned rows and / or columns, then 'flatten out' the grid in your head so that all rows and columns are visible, then the cell selection will work as you would expect in the flattened out version where only full rectangles can be selectable.

{% gridExampleRunner title="Cell Range Selection and Pinned Areas" name="range-selection-pinned-areas" /%}

## Highlight Headers

It is possible to highlight the Grid Headers that are part of a range by setting the `cellSelection.enableHeaderHighlight` to `true`.

```{% frameworkTransform=true %}
const gridOptions = {
    cellSelection: {
        enableHeaderHighlight: true,
    }
}
```

{% gridExampleRunner title="Cell Range Selection Header Highlight" name="range-selection-highlight-headers" /%}

## Copy Cell Range Down

When you have more than one row selected in a range, pressing keys {% kbd "^ Ctrl" /%}+{% kbd "D" /%} will copy the top row values to all other rows in the selected range.

By default, the Value Formatter and Value Parser will be used whilst copying the range via the [Use Value Formatter For Export](./value-formatters/#formatting-for-export) and [Use Value Parser for Import](./value-parsers/#use-value-parser-for-import) features.

## Bulk Cell Edit

When [Cell Editing](./cell-editing/) is enabled, and a cell range is selected, typing to enter a new value and pressing the {% kbd "^ Ctrl" /%}+{% kbd "↵ Enter" /%} keys will set the newly provided cell value to all the editable cells in the selected cell range.

## Delete Cell Range

When [Cell Editing](./cell-editing/) is enabled, pressing the {% kbd "Delete" /%} key will clear all of the cells in the range (by setting the cell values to `null`). If your column uses a `valueParser`, it will receive an empty string (`''`) as the new value.

This will also emit the following events:

{% apiDocumentation source="grid-events/events.json" section="editing" names=["cellSelectionDeleteStart","cellSelectionDeleteEnd"] /%}

## API Reference

{% note %}
The cell selection state can be saved and restored as part of [Grid State](./grid-state/).
{% /note %}

Here you can find a full list of configuration options available in `'cell'` mode.

{% interfaceDocumentation interfaceName="CellSelectionOptions" config={"description":""} /%}

## Next Up

Continue to the next section to learn about the [Range Handle](./cell-selection-handle).
